docs: rewrite README for adoption; realign stated status (no bump) - #166
Merged
Conversation
The README described a repository with no installer and closed with "Please do not adopt it yet", while @pharn-dev/pharn was published and working. Verified by running it rather than inferring: `npx @pharn-dev/pharn@latest init` detected the ssr archetype and installed the product commands, the write-gating hooks, the floor, the contracts and a pinned pharn.config.json. Four claims corrected against live state rather than restyled: - "denies any agent edit" — not defensible; the hook's own bounds state that Bash-tool writes bypass PreToolUse entirely. Now stated with its bound. - "secrets screened at the plan gate" — scan-plan-secrets.mjs is genuine floor, but runs at grill, and grillers never gate. Restated as detection that surfaces, not a gate. - "every write confined to its declared scope" — fix #7 gates Write|Edit|MultiEdit only. Restated with that surface named. - the comprehension-debt and RCT citations — the linked post makes no coinage claim and credits prior work; the study measured a lab exercise in which nothing was shipped (50% vs 67%), so "~17% lower on code they shipped" was wrong in both halves. Coinage attribution dropped, number no longer cited. The third hero guarantee survived and is now named with its checker: check-build-complete.mjs feeding check-verify.mjs yields INCOMPLETE for a plan-declared file the build never wrote. Review caught one blocking-severity defect, fixed inside the increment: the build hardcoded two capability counts into unguarded prose that the generated CURRENT-STATE block already owns — in the increment whose plan forbade exactly that and cited L20/L24. See .dev/features/readme-adoption-rewrite/ REVIEW.md Lens 1; check-plan-lessons.mjs was GREEN throughout, as documented (it verifies the declaration, never the application). No SKILLS_VERSION bump: repo-meta only, no product-surface bytes. Gates: npm run check exit 0; FLOOR GREEN (36 capabilities); regress no-regressions; verify PASS across nine gates. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LozSBkwtGWc1Rz5Ufv8yj
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The README described a repository with no installer and closed with "Please do not adopt it yet", while
@pharn-dev/pharnwas published and working. This rewrites the rootREADME.mdto the S1–S10 adoption structure and realigns the stated status inSECURITY.md,CONTRIBUTING.mdandCLAUDE.md.No
SKILLS_VERSIONbump — repo-meta only, no product-surface bytes. Badge stays2.7.14.Verified, not inferred
npx @pharn-dev/pharn@latest initwas run to completion in a scratch repo (its confirm prompt needs a TTY). It fetched frompharn-dev/pharn-oss, detected thessrarchetype, and landed the product commands, the write-gating hooks, the floor, the contracts and apharn.config.jsonpinningskillsVersion 2.7.14and commit71e71ee.Four claims corrected rather than restyled
PreToolUseentirelyscan-plan-secrets.mjsis real floor, but runs at grill, and grillers never gateWrite|Edit|MultiEditonlyThe third hero guarantee survived and is now named with its checker:
check-build-complete.mjs→check-verify.mjsyieldsINCOMPLETEfor a plan-declared file the build never wrote.The defect the loop caught in this increment
Review raised one blocking-severity finding: the build hardcoded "Thirteen grillers" / "Twenty-two review lenses" into unguarded prose that the generated
CURRENT-STATEblock already owns — in the increment whose own plan forbade exactly that and cited L20 and L24 for it.check-plan-lessons.mjswas GREEN before and after, exactly as documented: it verifies the declaration, never the application.Fixed inside the increment and recorded rather than smoothed over —
.dev/features/readme-adoption-rewrite/REVIEW.md, Lens 1.Gates
npm run check→ exit 0 (all 8 gates, 1620/1620 tests)node pharn/floor/validate.mjs .→FLOOR: GREEN — 36 capabilities checked in "."/pharn-dev-regress→no-regressions; scope partition exit 0, no escape/pharn-dev-verify→PASS,failing_gates: []across nine gatesCURRENT-STATEblock moved byte-exact (md5 unchanged), sodocs:generatewas never neededReviewer note — what the gates do NOT cover
No gate in this repo reads prose for truth. They verify formatting, byte-equality, badge agreement and tests. Every factual claim rests on the live-state discovery recorded in
.dev/features/readme-adoption-rewrite/PLAN.mdand on human reading. Please read the rendered README.Known residual (not fixed here)
THREAT-MODEL.mdandLIMITS.mddo not land in an install, and the README now discloses it. Investigating that surfaced a separate live defect in this repo: the shipped hook still lists both inDEFAULT_PROTECTED, so a user's install denies agent writes to two root paths PHARN never installed — over-blocking their own same-named files with no compensating benefit. Out of axis here; a scoped increment prompt for it is drafted.🤖 Generated with Claude Code
https://claude.ai/code/session_019LozSBkwtGWc1Rz5Ufv8yj